home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Collection of Tools & Utilities
/
Collection of Tools and Utilities.iso
/
c
/
recio202.zip
/
tutor.txt
< prev
next >
Wrap
Text File
|
1994-05-05
|
17KB
|
455 lines
Title: A TUTORIAL INTRODUCTION TO THE C LANGUAGE RECIO LIBRARY
Copyright: (C) 1994 William Pierpoint
Version: 2.02
Date: May 5, 1994
1.0 STDIO AND RECIO
The program many people learned when first introduced to the C programming
language was the "hello, world" program published in Kernighan and Richie's
"The C Programming Language." And the first line of that first program,
#include <stdio.h>
tells the compiler that the functions and macros provided by the standard
input/output library are needed for the program. The "hello, world" program
uses the powerful printf statement for output. The counterpart for input,
scanf, looks deceptively like printf, but unfortunately has many ways to
trap an unwary programmer. These include failure to provide the address
of an variable, size of argument mismatched with the specification in the
format statement, and number of arguments mismatched with the specification
in the format statement.
Suppose you use a library that defines a boolean type as an unsigned
character. You develop an output module that writes variables of type
boolean to a file,
/* output */
boolean state=0;
...
fprintf(fp, "%6d", state);
where fp is a pointer to FILE. Once you get the output module working, you
decide to develop the input module to read back into the program the data
you wrote to disk.
/* input */
boolean state;
...
fscanf(fp, "%d", &state);
So, is this ok? On one compiler this worked consistently without problems,
but on another compiler, it overwrote the value in another variable. Why?
Because fscanf expects the address of an integer, not an unsigned char.
One compiler overwrote the adjoining memory address and the other compiler
apparently did not. And since compilers don't do type checking on functions
with variable number of arguments, you don't get any errors or warnings. That
is what is so infuriating about this type of error. You see that another
variable has the wrong value, you check all the code that uses the other
variable, and you can't find anything wrong with it. In the midst of
development, it is hard to imagine that the problem is caused by code that
has nothing to do with the variable containing the bad value.
The recio (record input/output) library takes a different approach to input.
To input the boolean variable using the recio library, just write
/* input */
boolean state;
...
state = rgeti(rp);
where rp is a pointer to REC (the recio structure analogous to the stdio
FILE structure). The rgeti function gets an integer from the input and the
compiler converts it to a boolean when it makes the assignment. No need to
worry about crazy pointers here!
Since virtually every program has to do input or output, the stdio library
is very familiar to C programmers. Many functions in the recio library
are analogous to the stdio library. This makes the learning curve easier.
Analogous stdio/recio components
stdio recio
--------- ---------
FILE REC
FOPEN_MAX ROPEN_MAX
stdin recin
fopen ropen
fclose rclose
fgets rgetrec
fscanf rgeti, rgetd, rgets, ...
fprintf rputi, rputd, rputs, ...
clearerr rclearerr
feof reof
ferror rerror
2.0 EXAMPLES
2.1 Line Input
One of the first things you can do with the recio library to is to substitute
rgetrec() for fgets() to get a line of text (record) from a file (or standard
input). The advantage of rgetrec() is that you don't have to go to the
trouble to allocate space for a string buffer, or worry about the size of the
string buffer. The recio library handles that for you automatically. The
rgetrec function is like fgets() in that it gets a string from a stream, but
it is like gets() in that it trims off the trailing newline character.
The echo program demonstrates the use of the rgetrec function.
/* echo.c - echo input to output */
#include <stdio.h>
#include <stdlib.h>
#include "recio.h"
main()
{
/* while input continues to be available */
while (rgetrec(recin)) {
/* echo record buffer to output */
puts(rrecs(recin));
}
/* if exited loop before end-of-file */
if (!reof(recin)) {
exit (EXIT_FAILURE);
}
return (EXIT_SUCCESS);
}
The echo program reads standard input using recin, the recio equivalent to
stdin. For output the recio library provides recout, recerr, and recprn.
The rgetrec function returns a pointer to the record buffer, but the echo
program did not use a variable to hold a pointer to the string (although
it could have). Instead, the record buffer was accessed through the rrecs
macro, which provides a pointer to the record buffer.
Since rgetrec returns NULL on either error or end-of-file, your program
needs to find out which condition occurred. You can use either the reof
function or the rerror function to determine this. The echo program uses
the reof function; the wc program in section 2.2 uses the rerror function.
The echo program just exits with a failure status if an error occurred
before the end of the file was reached.
2.2 Line, Word, and Character Counting
The power of the recio library comes from its facilities to break records
into fields and from the many functions that operate on fields. Because
the default field delimiter is the space character (which breaks on any
whitespace), the default behavior is equivalent to subdividing a line of
text into words.
The wc program counts lines, words, and characters for files specified
on the command line.
/* wc.c - count lines, words, characters */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "recio.h"
#define SIZE_T_MAX (~(size_t)0)
main(int argc, char *argv[])
{
int nf; /* number of files */
REC *rp; /* pointer to open record stream */
long nc, /* number of characters */
nw, /* number of words */
nl; /* number of lines */
/* loop through all files */
for (nf=1; nf < argc; nf++) {
/* open record stream */
rp = ropen(argv[nf], "r");
if (!rp) {
if (errno == ENOENT) {
printf("ERROR: Could not open %s\n", argv[nf]);
continue;
} else {
printf("FATAL ERROR: %s\n", strerror(errno));
exit (EXIT_FAILURE);
}
}
/* initialize */
nc = nw = 0;
rsetfldch(rp, ' ');
rsettxtch(rp, ' ');
/* loop through all lines (records) */
while (rgetrec(rp)) {
/* count number of characters in line w/o '\n' */
nc += strlen(rrecs(rp));
/* count actual number of words (fields) */
nw += rskipnfld(rp, SIZE_T_MAX);
}
/* if exited loop on error rather than end-of-file */
if (rerror(rp)) {
printf("ERROR reading %s - %s\n",
rnames(rp), rerrstr(rp));
exit (EXIT_FAILURE);
}
/* get number of lines (records) */
nl = rrecno(rp);
/* adjust nc for operating system line termination character(s) */
#if defined (__MSDOS__) || (MSDOS)
nc += nl + nl; /* carriage return and linefeed for each line */
#else
nc += nl; /* newline for each line */
#endif
/* output results */
printf("%s: %ld %ld %ld\n", rnames(rp), nl, nw, nc);
/* close record stream */
rclose(rp);
}
return (EXIT_SUCCESS);
}
If ropen() fails, the wc program goes to the trouble to check errno for
ENOENT rather than just assuming that the failure was caused by a missing
file.
The wc program also sets the field and text delimiters even though it is
unneccessary here since they are the same as the default values. If you
wanted to read a comma-delimited file, you could set the the delimiters to
rsetfldch(rp, ',');
rsettxtch(rp, '"');
which allows you to also read text fields containing